The 'classic' method of scripting a connection attempt goes something like this:
tell application "Black Night 1.0.4"
open helper "Atlantis"
wait until connection of document "Atlantis" becomes active timeout 50
if not result then return "Unable to Connect"
return ""
end tell
If the connection attempt failed, then the "Wait" command would timeout after 50 seconds and get captured as a generic failure.
This script will still work, but now you can also do this:
tell application "Black Night 1.0.4"
open helper "Atlantis"
wait until connection of document "Atlantis" becomes idle timeout 50
if not result then return "Out to Lunch"
set localResult to errcode of connection of document "Atlantis"
--- -128 is user canceled
if localResult is equal to -128 then return "You canceled !"
--- 0 is usually success, you may want to check the status though
if localResult is equal to 0 then return ""
--- some other error - report it
return localResult
end tell
The change is the addition of the "errcode" property which returns the error code returned by the connection tool after the last connection attempt. Note that connection tools are rather sparodic in the manner in which they return error codes and hence this is not 100% reliable. If you're really paranoid then you should check the status of the connection to make sure it really is open.
The other change is the "status" property now includes an enumeration "idle", which means that it's either connected or not connected. This enumeration is only referenced by the wait command (i.e. if you read the status directly - you will not get "idle" returned).
